Business Analyst Community & Resources | Modern Analyst

Eliminating Software Documentation

Leslie — Mon, 22 Mar 2010 10:25:00 GMT

Not a suggestion for eliminating the process of documenting a software application, but rather a proposed for replacement of the documenting activity and manually produced documents with something more manageable and less likely to frighten the development team.

Initiative for this work comes from a number of discussions I have been following and also an expansion of ideas I have recently documented about best practices for software development.

1.1 Introduction

Developers nightmare – you have spent endless sleepless nights thinking about finally getting your software ready for deployment. It compiles and runs without error. It has been tested and passed user acceptance testing. It is finally ready to be released .. but, you are told that it may not be deployed until the documentation has been approved.

You have been neglecting those 200 page templates that have lying in your inbox while getting your software to compile. Now you have to spend another umpteen nights in the office writing about what it is that you have produced – yawn!

This is not a task that is going to enthuse you to do a quality job. You will probably do your best to get the documents approved asap .. anything to get your code deployed so that you can spend some quality time with family and friends.

Is this a situation you have found yourself in? I have. When I was younger, I quickly learned that this is the downside to the job of being a software developer.

Supposing though, that all you needed to do to get your software deployed, after it was already ‘working’, is to check that everything is up-to-date and consistent, post your deliverables to a ‘release’ area and organize a review meeting, with follow-up!

The following is not meant to be a complete solution, but some ideas for eliminating that boring ‘produce documentation’ task, that always seems to follow any software development effort, not only for programmers, but any member of a development team effort, including analysts, architects, testers, UI designers and any other role that produces work that needs approval.

1.2 What

Instead of identifying a document for delivery as part of a software effort, I propose to break the document into 2 components:

· the document template, and

· document contents.

Where a document has previously been identified as a deliverable, identify the document template as a deliverable. In many cases this allows for several previously deliverable documents to be replaced with a single deliverable – the template that is subsequently populated with the document contents.

This leads to 3 major activities:

· creation and management of document templates,

· production of the contents populating the template(s),

· compilation of the document from its template and contents.

1.3 How

1. Identify the stakeholders that require information that is not part of the compilable software.

2. For each stakeholder, list the information that they require in order to approve the product.

3. Work with each stakeholder to create (or select from a library) the format for a template that is an acceptable method of presenting the required information.

4. Identify dates for the delivery(s) of each template and its needed contents, and track the progress of each.

1.4 Process

For each task under How consider something along the lines of the following activities.

1.4.1 Identify Stakeholders

Stakeholders are anyone within or outside of the development team with an interest in the progress of the product. Anyone not requiring information from the product development effort, is probably not a stakeholder. Typical examples are:

· End users – who would like to see early examples of the user interface and a description of how it operates.

· Project managers – who want to be able to track the progress and effort of everything in the product repository.

· Testers – who will need to be able to access the product requirements in order to maintain test cases.

· Business owners – who will want to k now the scope of the product releases and which requirements are going to be satisfied at each release.

1.4.2 List Information

In the past when each stakeholder has been asked for their needs, they would typically turn to an existing document for reference. This document is often stripped of its current contents and has its contents replaced with information for the new product, without consideration for whether the information is ‘really’ required.

Instead, try starting with traditional document templates and work with the stakeholder to:

1. identify which sections they ‘really’ need,

2. describe the reason for this need,

3. write a description of what is documented in order to satisfy this need,

4. identify a product development timeframe for this information to be available.

Each item of information is given a location in the product repository, and duplicate information is consolidated.

Create a public interface location that always contains the latest version of each piece of information. This is the ‘release’ area.

1.4.3 Accessing Information and Publishing Documents

In many cases a stakeholder may not even require that information is presented in a traditional document form. If the stakeholder is comfortable with the repository used to contain the information, all they may need is easy access to that information.

Using a document sharing tool, such as SharePoint or a Wiki, it is relatively easy to create customized user pages that accesses only the information the stakeholder needs in a layout that makes it easy to access that information.

Alternatively, a scripted documentation tool, such as SoDA, may be used to parse a template and automatically populate it with information from the repository. Give the ability to produce the document to the stakeholder, and the development team need not be concerned with producing documents. They simply inform the stakeholders that a new version is ready for review, publish the information to the release location that the script accesses, and the stakeholder can run the script to extract the required information whenever it is convenient for them.

1.4.4 Delivery Dates And Tracking Progress

Attributes may be added to each repository element for delivery dates, assigned responsibility, progress, stakeholder(s) and a description of its contents. A reusable placeholder is created for each delivery type containing default information for each attribute.

1.5 Conclusion

As stated, the idea is not necessarily to remove documentation from the project, but to reduce the usage of the word on a development effort, and put emphasis on the ‘required’ contents and less on the document itself.

Advantages of this type of approach might be:

· The removal of unwanted/unused documentation.

· Tracking by more manageable chunks.

· Elimination of duplicate information.

· Removal of confusion over what is ‘most current’, since there is a single delivery area for every unique deliverable.

· An end to the developers nightmare of having to produce reams of documentation, after the ‘fun’ part is over.

I recognize that not all deliverable documents can necessarily be replaced in this manner. But maybe it is a start towards removing the dreaded word ‘documentation’ from a project’s deliverables list and maybe a compromise between agile proponents of minimizing documentation and those requiring documentation according to some sort of standard.

1.6 References

Links to articles that inspired this work.

http://www.linkedin.com/groupAnswers?viewQuestionAndAnswers=&discussionID=14867479&gid=1976291&trk=EML_anet_qa_ttle-0Qt79xs2RVr6JBpnsJt7dBpSBA

Best Practices

Create a product information repository that contains everything that is going to be shared amongst product stakeholders. Using this repository:

Best Practices - Ad Hoc Procedures

Leslie — Thu, 18 Mar 2010 06:16:00 GMT

Ad Hoc Procedures

My belief is that software development should be more of a science and contain as little artistry as necessary. It is great to come up with ingenious processes and guidelines for developing your software, but if they impact your colleagues you must get buy-in from everyone who is impacted before you start using them.

Some people achieve satisfaction by getting a compliment for a ‘job well done’, some for a ‘working really hard’ others for ‘being a team player’. Nothing gives me more pleasure than having a colleague answer ‘Yes’ to the question, “Did I make your life easier?”.

Recommended procedures for working with documents should be documented, available and approved by all users of those procedures. Examples of these procedures include:

Location of document templates and how to access them.
The purpose of the document template and where to enter information into the template.
Documentation numbering and versioning conventions.
How to check out from and check in to a document repository system.
How to use the product or project glossary.
The purpose of the styles and properties that are used by a document.
The process for baselining, or creating a new version of a document.

Document your procedures and make sure that everyone that needs them understands them and has easy access to their documents.

Further articles will expand upon the obove bullets, with examples.

[1] This was not always the case .. when I first started programming I invented some extremely ingenious and complex software procedures, that I was proud of at the time. I look back at those days and cringe.

Editor's Note: Check out the list of all related best practices.

Best Practices - Document Content

Leslie — Mon, 15 Mar 2010 04:47:00 GMT

Unnecessary Documentation

The first section that I look for in a document, is the paragraph that describes ‘who this document is written for’ and ‘what benefit they can expect to gain by reading this document’. If I do not see my role, or I do not see any benefit from me spending time reading the document, then I have to ask myself the question, ‘Do I want to read this document?’ I want this information to be displayed to me asap, such that I waste as little time as possible, reading a document that is of no interest to me.[1]

When I review a document or document template, another task that I might perform, is to consider each section in the document and ask the question, “Who asked for this information to be entered into this document?’ Or, another way of putting the question is; Who is going to read this and get value from it?[2]

Typical subsequent sections of a document I have seen that need this question applied include:

Document History – How many readers want to know what changed between versions from 1.1 through to 1.15?
Definitions and acronyms – leave them in the glossary, nobody needs to read these in the document. If anything I want to be able to reference these while reading the document without having to leave the current page. (See also ‘Duplication’.)
References – Put the reference in the section that uses it. I do not need to see a separate page containing a complete list of document references. I am not going pull up all the referenced documents and have them prepared in case I come across documentation that makes reference to one of them.

Before you document something, find out who it is that needs this information documented.

Which leads me to ..

Document Content Organization

On a related issue: There are tools for recording document versions. Any decent tool that is intended as a central repository for files of any type will record the version of the document and allow the author to add comments to the version. Such tools include SharePoint, LiveLink and ClearCase amongst many others. So why is it that when I open most documents, one of the first things to be presented for my reading pleasure is a table containing a version history. Honestly, I have seen version histories that span many pages and are quite detailed. They explain every change that has been made to the document over the last Millennium. Who wants to read this stuff, and why is it the first information that is presented to the reader after getting past the front page? If we are using a document management system on this project, (and I certainly hope that we are) all of the version history information should be documented inside the tool. Why is it being repeated in the document?

Many years ago, before the advent of intelligent document comparison tools, this information may have been useful in the front of the document. It allowed to reader to determine which parts of the document have changed since the last time they read it. Today, any Word processor worth purchasing will inform you what has changed since the last time you reviewed the document.

I realize that there are some roles on the project to whom this information is important, QA or auditors, for example. If you must publish this information with the document, put it in an appendix to the document, or better still, extract it from your document management tool into its own document. Then distribute the version history document only to those people that want it.

Now that the version history is out of the way, what do we now see when we open the front cover of the document? The table of contents. It is useful to be able to easily locate this, but I question whether it is the first piece of information that I want to read. What I need to know, as soon as possible is, ‘Should I be reading this document?’ What is going to answer this question – the Introductory material in section 1.

The first question I want answered is; Is this document describing a system that I am interested in?
The second question is; Is the information in this document pertinent to my relationship with the application?
The third question is; What information am I going to get from this document?
Fourthly: What is my responsibility towards the information in this document?

Hopefully, the answers to these questions become apparent as soon as I open the front cover of the document.

Put the appropriate information in the appropriate place and avoid showing unnecessary information to the wrong people.

[1] Typically, I expect to see this section, right after the document overview, which tells me that I am not a part of this project anyway.

[2] If the content is relevant, then I might ask if this information is implied within the section that describes the ‘Audience’ for the document.

Editor's Note: Check out the list of all related best practices.

Best Practices - Inconsistent Documentation

Leslie — Sat, 13 Mar 2010 05:40:00 GMT

If you are writing a letter to your mother, it is fine to create a new a new blank document, type your random thoughts, add highlighting, colors and emphasized text where you want to make and get a point across, and basically format the document with any creative ideas that you feel appropriate.

When working with documents in the workplace, ad hoc formatting is probably not appropriate. Yet I see so many requirements and other technical documents that were written by people who thought that they were writing a letter to their parents.

Imagine if every programmer on the development team wrote source code using their own personal coding standards. Nobody would be able to maintain someone else’s code. It should be the same with documentation. Every document should be written from a predefined document template that includes documentation standards (instructions for use), a consistent set of styles and properties.

The problem not only applies to textual documents, but also to diagrams. UML for example, defines a set of artifacts in terms of a set semantics and rules that apply to that artifact. (As far as I am aware) the icons used to represent an artifact are not defined within UML standards. Not only that, but UML allows the stereotyping of defined artifacts, which in turn leads to a customized representation of the artifact.

An example, I might be, using an arrowhead to indicate the initiator of a use case (which I do), and someone else using a dashed line to indicate the same thing. Now there needs to be an explanation in each document of the meaning of which notation that is being used. Not only that, but if both diagrams contribute to the same document, you are going to confuse your readers.

Use a set of rules for identifying a particular meaning on a diagram. If there is no rule for it, then make one up and explain what the particular notation means (although the more project rules there are , the less explanation needs to be added to the diagram or document). Say for example, you wish to highlight parts of a diagram to indicate that they are candidates for change, but there are no project specific rules for indicating how to highlight changing components. Then go ahead and shade the items (or whatever highlight you prefer) and explain what the highlighting means.

Which leads me to; the number of times I see a figure in a document without, not just a description of the figure, but not even a reference to it. Why did you put this figure here, if you are making no reference to it?

If there are 2 ways of doing something, pick one that works, describe it and stick with it for the length of the project.

Editor's Note: Check out the list of all related best practices.

Best Practices - Ambiguity

Leslie — Sat, 13 Feb 2010 05:34:00 GMT

How many times have you experienced a disagreement between colleagues, only find out later in the project that they were both correct. Chances are that they were using the same word, but both had different ideas of its meaning. [1]

I can derive hours of entertainment by playing word games with my friends, by picking a word they are using and purposely give it a definition that they are not thinking of. The important thing is that no one definition is incorrect, but it may be different.

For example, ‘Closing the door’; everyone knows when a door is closed and when it is not – don’t they? I might argue that no 2 people have exactly the same definition of a closed door. I might argue that a door that is ajar by an inch or so is actually closed. This is not strictly incorrect unless all parties involved in the conversation have agreed to a definition of a ‘closed’ door.

Obviously, this is not the sort of discussion that you want to have in the work place, but it is going to happen if not everyone has the same definition for an ambiguous term. Ok, you may say, but everyone in the work place has a pretty good idea (or at least a close idea) of what constitutes a closed door, such that we do not have to define it. Well if you are working for a word processing software company – yes; but if you are writing software for an application that controls submarines, and you want me to ride on that sub, I hope that the word ‘closed’ when referring to doors, was well-defined early in the development process.

My recommendation is to maintain a glossary of commonly used terms on your project that could cause confusion if open to several interpretations. We know that ideally requirements should not contain adjectives or adverbs, such as near, far, slowly or quiet. Sometimes we need to use these words on a project, in which case they should be defined in a glossary. For example; if we often use the word slowly, then define it as; Slowly – implies that the vehicle is traveling at less than 10% of its maximum speed.

I find that a RequisitePro project works well for maintaining a glossary of terms. MS Excel and other spreadsheet applications may work equally well; so long as you can order terms, give them several attributes (acronym for example) and link them (as synonyms of each other, for example).

Next time you are in a disagreement with anyone (be it at work or at your local), listen to the words that they are using and try to figure out which ones are having a different definition applied to that which you are using. You’ll come to an agreement eventually (that is of course unless their objective in arguing is to maintain the argument).

Whenever possible, do not use a word (acronym or term) that is ambiguous, because you can be sure more than one interpretation will be used.

[1] I’m sure that we have all experienced this game as children. Leslie, I thought that I told you to tidy your room .. it is tidy .. no, it isn’t.

Editor's Note: Check out the list of all related best practices.

Best Practices - Duplication

Leslie — Sat, 13 Feb 2010 04:22:00 GMT

How often do you see the same piece of information documented in 2 places? I am used to seeing requirements information copied into design documents; whole sets of requirements being copied into a test repository and diagrams copied from one document to another. Unless you employ a strict change management control system that includes a traceability scheme, this sort of practice is going to prove expensive, for 2 main reasons:

The work of maintaining information is being done twice.

More expensively, if one artifact changes and the other doesn’t, how do we know which is correct? [1]

Employing an automatic update scheme, a traceability scheme which shows when something has changed or a strict configuration management scheme which prevents artifacts from being changed, will go some way to solving the duplication problems, but again they are expensive.

Rather than spending time and money in trying to control duplication; I recommend, ‘Don’t Do It’. Here are some schemes that can be used to prevent duplication:

Put the information in a central repository and reference it with hyperlinks.

If you must have the information displayed in two separate places, use Object Links and Embedding (OLE). Extract the information from both artifacts, place it in its own document and embed the document as an OLE.

Use document generation tools, such as SoDA, to insert duplicated information into your documents.

Ask yourself the question; ‘Do I need to put this information here?’ Or, ‘Can I reference the same information, located somewhere else?’

Do not copy, either use a link or make a reference if you absolutely must have it here.

[1] The worst example of this was on a contract where the test team did not like the way the developer’s document repository was organized, so they copied the developer’s documents into their own repository. The wrong tests were consistently being executed against the code.

Editor's Note: Check out the list of all related best practices.

Best Practices

Leslie — Fri, 12 Feb 2010 08:10:00 GMT

This following blogs contain rants and recommendations for good practices, useful not only for when delivering software, but that can also be used any time organization is required.

The most common improvements that can be leveraged on any (some on every) development process it has been my experience to be involved with, are the following:

Duplication - Copying and pasting, work (text or diagrams) from one place (or document) to another.

Ambiguity - Using the same term(s) with more than 1 meaning on the same project.

Inconsistent Documentation - Documents that supposedly describe the same information (or have similar purposes), but have different content. Deviating from the approved document template.

Unnecessary Documentation - The creation of documentation, without first identifying an audience.

Document Content Organization - Related to unnecessary documentation. This rant is concerned with putting the right information in the right place in the document.

Ad Hoc Procedures - Concerns having a standard set procedures for handling files and making sure that everyone on the project understands how to use them.

I will discuss each point in detail in my following posts ..

Thoughts on Specifying Requirements

Leslie — Fri, 12 Feb 2010 08:04:00 GMT

Requirements

I have been working with requirements for more than 20 years. To be honest, it was several years before I understood the true purpose of requirements. The enlightenment came about when I was tasked with documenting a presentation to my colleagues that described the characteristics of a ‘good’ requirement. The characteristics that the team came up with included:

Complete – A functional requirement should describe all observable inputs, all observable outputs, when it can occur, who (actor that) is allowed to initiate the requirement and the maximum time that the requirement is allowed to complete.
Consistent – The requirement should not be in conflict with any other requirements for the project. For example, if one requirement states that all user inputs will be processed within 5 seconds of entry and another requirements states that system shall respond to a particular user input within 10 seconds, there is a conflict in the requirements.
Correct – Are the requirements specifying a solution that the business wants implemented?
Design independent – If there is another way of specifying the requirement which will result in a different solution to the problem, then it probably contains design information and should be abstracted out to allow for all possible design decisions. For example, stating that when the main window is closed that the system will logout the user etc, is too detailed. Supposing we decide not to build a windowed application? A better way to abstract the requirement would be to say that when the user exits the application that they will be logged out, etc.
Feasible – Is it possible to implement the requirement within the specified time and budget? (And, we might want to ask if there is there a positive return on investment (ROI) for implementing this requirement?)
No negative requirements – Stating the system ‘shall not’ do something is either untestable or irrelevant. The requirements state what the system will do; anything else is out of scope. For example, instead of stating that something shall not be ‘red’, state the colors that it may take. Irrelevant example; stating that the system ‘shall not’ allow a user to view user information, is already covered by a requirement that an administrator shall be able to view user information. The fact that it has been stated that administrators may view this information, excludes all other actors, unless explicitly stated. A rule of thumb is that the system does nothing unless it is stated as a function of the requirements.
Relevant – Is the requirement in scope for the current effort.
Testable – Is it possible to define specific ranges of inputs and outputs for the requirement such that when the implementation of the requirement is executed all inputs cause the system to produce the specified outputs, otherwise the implementation of the requirement fails?
Unambiguous – The requirement should not contain any words that are open to interpretation. This includes all adjectives and adverbs, unless they are clearly defined in a project glossary. For example, the system shall allow ‘many’ users to change their profile. Unless the word ‘many’ is explicitly defined this requirement has little meaning; and it can be satisfied by allowing exactly 2 users to change their profile and no more.

Functional Requirements

In addition to the above, functional requirements include the following characteristics:

Precondition (optional) – when can the functional requirement execute? The precondition specifies what state the system must be in before the requirement may be initiated. Not all functional requirements are able to execute at any time. If using a use case approach to writing functional requirements, the use case precondition states what use case(s) must have completed prior to this use case being able to initiate, and each step in the use case has an implied precondition, which is the previous step in the use case. (Sometimes the precondition may be implied by the wording of the requirement, in which case it does not have to be explicitely stated.)
Time to complete – if a functional requirement does not have an associated maximum time to complete, then if the implementation of the requirement does nothing it will never fail testing. If it never fails testing and never does anything it will never get deployed into production. Again, using a use case approach, the whole use case may be given a time to complete, or you may specify time to complete for individual steps. If a group of steps are assigned a time to complete, and that time expires during testing, then every step in that grouping is considered to have failed the test.

Non-Functional Requirements

Non-functional requirements additionally include the following characteristics:

Reference to a functional requirement – non-functional requirements place constraints upon functional requirements. Functional requirements may include the meaning of the non-functional requirement in their specification. The reason non-functional requirements are specified separately is because they often impact many functional requirements. We do not want to duplicate the requirement. Therefore it is called out as a separate requirement and references the functional requirements that it impacts.

Definition of a Functional Requirement

From Wikipedia: ‘In software engineering, a functional requirement defines a function of a software system or its component. A function is described as a set of inputs, the behavior, and outputs (see also software).’

When not employing use cases, I use a template for specifying requirements of the following format: 'When' in a certain state* 'and' 'upon’ some externally visible event occurring (the trigger), ‘the system shall’ do something externally visible, ‘within’ a certain time frame.

['When' in a certain state is optional, and if omitted means that the requirement is valid in under all circumstances, i.e. it has no precondition.]

For example, 'When' the ATM is free, 'and upon’ a customer inserting a valid debit card into the ATM slot, ‘the system shall’ request that the customer input their PIN through the ATM user interface, ‘within’ 5 seconds.

(The 5 seconds of course applies to the system and not to the customer entering their PIN.)

Here are some examples of requirements that do not satisfy the template. See if you can figure why before reading my answers.

When requesting a customer PIN, and upon a customer entering their PIN through the ATM UI, the system shall verify that the PIN is correct for the card, within 5 seconds.
Upon verification of the customers PIN, the system shall inform their customer that they may select an action from the ATM UI, within 5 seconds.
Upon dispensing cash to a customer, the system shall send a message to the Banking System requesting that the customer’s account balance be deducted by the amount dispensed.
When a customer card is inserted, and upon the Banking system receiving a deduction message, the system shall give the customer their card back, within 5 seconds.
Upon a customer entering the 'Display Balance' command, the system shall request the customer balance from the Banking system, within 5 seconds.

In my opinion these requirements contain the following errors:

‘Verify the PIN’ is not an externally visible action. If the PIN is valid, the selection screen will be displayed. If the PIN is invalid, an error message will be displayed. The first case was already covered by the original requirement when it included the word ‘valid’. We need to add another (separate) requirement to cover the invalid situation.
The trigger is not externally visible. We cannot observe the system verifying the customer PIN. In fact the act of ‘verifying’ the PIN is a design decision. Our designers might equally decide that the PIN is verified by the Banking System. In fact, in reality, it probably is.
No time frame specified. The banking system is going to lose a lot of money if the ATM sends out deduction requests once a year.
The trigger is not an event that the ATM system can recognize. The Banking System has to somehow inform the ATM system that it received the message. It is upon reception of this event that the requirement initiates.
No precondition. The customer must first have entered a valid PIN, otherwise the system cannot be sure whose balance to request.

In my next post I intend to identify some best practices for working with requirements..